Reference for showing Kanzi Engine plugin custom types in Kanzi Studio

You can use Kanzi Engine plugins to create custom property types and messages using the Kanzi Engine API, and use them in Kanzi Studio.

To pass to Kanzi Studio information about the custom property types and messages you create in a Kanzi Engine plugin, you declare metadata that describe these property types and messages. The metadata enable Kanzi Engine plugin users to interact with the plugin content in Kanzi Studio. For example, metadata defines the type of Kanzi Studio property editor for setting a value for a property, and the set of values to select from.

Declare only the metadata you need. Kanzi Studio assigns the default values to the attributes that you do not set.

This table lists the metadata attributes you can use.

Attribute	Description	Use for property types	Use for message types
`displayName`	Name of the property or message the way it is shown in Kanzi Studio	x	x
`tooltip`	Tooltip for the property or message	x	x
`category`	Property, trigger, or action category name the way it is shown in Kanzi Studio	x	x
`valueProvider`	Source of the possible values for the property that Kanzi Studio lets the user select from	x
`host`	Node types for which Kanzi Studio suggests the property, and whether Kanzi Studio adds the property automatically or lets the user add it	x
`editor`	Type of Kanzi Studio editor used to set the value for the property	x
`DefaultValue`	Default value for the property	x
`LowerBound`	Lowest value the property can have	x
`UpperBound`	Highest value the property can have	x
`Step`	Amount by which the property value changes when a Kanzi Studio user edits it	x
`Sendable`	Whether Kanzi Studio shows the message as an action		x
`Listenable`	Whether Kanzi Studio shows the message as a trigger		x
`SortingIndex`	Position of the property within its property category in Kanzi Studio	x
`studioVisibility`	Whether the property or message is available in Kanzi Studio	x	x
`LegacyName`	Name of the property or message in the earlier versions of the plugin	x	x

displayName

Sets the name of the property or message the way it is shown in Kanzi Studio.

Syntax metadata.displayName = "name";

Values

name Name of the property or message the way you want to see it in Kanzi Studio

Examples

metadata.displayName = "Video Filename";

tooltip

Sets the tooltip for the property or message. Kanzi Studio appends to the tooltip text the Kanzi Engine name of the property or message in case the user needs it in scripting or application code.

Syntax metadata.tooltip = "text";

Values

text Tooltip text

Examples

metadata.tooltip = "Name of the video file to be played";

valueProvider

Sets how Kanzi Studio gets the possible values for the property to let the user select from.

Syntax metadata.valueProvider = "key:value";

Values

key

ProjectObject provides nodes or resources of specific type set by value.
PropertyType lists all available property types in a dropdown. Do not set value.
Do not set the editor type. Kanzi Studio sets the correct editor automatically.
Use PropertyType with string property types.
StringList provides a list to which the user can add items. Do not set value.
Do not set the editor type. Kanzi Studio sets the correct editor automatically.
Use StringList with string property types.
Enum provides a dropdown of options set by value, which is a list of items (string) and values (int) to which Kanzi maps the items.
Use Enum with int and enum property types.
Separate the items and values with pipes and the list of item-value pairs with semicolons:
Enum:string1|int1;string2|int2;...;stringN|intN

Examples

// Sets value provider to 3D nodes.
// (Kanzi Studio by default uses the Node 3D dropdown editor.)
metadata.valueProvider = "ProjectObject:Node3D";

// Provides a dropdown with all available property types.
// (Do not set the editor type. Kanzi Studio sets the correct editor automatically.)
metadata.valueProvider = "PropertyType";

// Provides a list to which the user can add items.
// (Do not set the editor type. Kanzi Studio sets the correct editor automatically.)
metadata.valueProvider = "StringList";

// Provides a list of directions along different dimensions which Kanzi maps to integers from 0 to 5.
metadata.valueProvider = "Enum : Left to Right|0;Right to Left|1;Top to Bottom|2;Bottom to Top|3;Near to Far|4;Far to Near|5";

// Creates a string reference to a node.
PropertyType<string> MyPlugin::NodeRefByStringProperty(kzMakeFixedString("MyPlugin.NodeRefByString"), "", 0, false,
                                                       KZ_DECLARE_EDITOR_METADATA
                                                       (
                                                           metadata.displayName = "Node Reference by String";
                                                           // When you set valueProvider to ProjectObject:Node3D, 
                                                           // Kanzi Studio automatically uses the Node 3D selector editor.
                                                           metadata.valueProvider = "ProjectObject:Node3D";
                                                       ));

// Creates a string reference to a prefab resource.
PropertyType<string> MyPlugin::PrefabRefByStringProperty(kzMakeFixedString("MyPlugin.PrefabRefByString"), "", 0, false,
                                                         KZ_DECLARE_EDITOR_METADATA
                                                         (
                                                             metadata.displayName = "Prefab Reference by String";
                                                             // When you set valueProvider to ProjectObject:PrefabTemplate, 
                                                             // Kanzi Studio automatically uses the Prefab template selector editor.			
                                                             metadata.valueProvider = "ProjectObject:PrefabTemplate";
                                                         ));

// Creates a shared pointer reference to a prefab resource.
PropertyType<ResourceSharedPtr> MyPlugin::PrefabRefBySharedPtrProperty(kzMakeFixedString("MyPlugin.PrefabRefBySharedPtr"), ResourceSharedPtr(), 0, false,
                                                                       KZ_DECLARE_EDITOR_METADATA
                                                                       (
                                                                           metadata.displayName = "Prefab Reference by Shared Pointer";
                                                                           // When you set valueProvider to ProjectObject:PrefabTemplate, 
                                                                           // Kanzi Studio automatically uses the Prefab template selector editor.		
                                                                           metadata.valueProvider = "ProjectObject:PrefabTemplate";
                                                                       ));

// Creates a shared pointer reference to a material resource.
PropertyType<ResourceSharedPtr> MyPlugin::MaterialRefBySharedPtrProperty(kzMakeFixedString("MyPlugin.MaterialRefBySharedPtr"), ResourceSharedPtr(), 0, false,
                                                                 KZ_DECLARE_EDITOR_METADATA
                                                                 (
                                                                     metadata.displayName = "Material Reference by Shared Pointer";
                                                                     // When you set valueProvider to ProjectObject:Material, 
                                                                     // Kanzi Studio automatically uses the Material dropdown editor.
                                                                     metadata.valueProvider = "ProjectObject:Material";
                                                                 ));

host

Sets the node types for which Kanzi Studio suggests the property, and whether Kanzi Studio adds the property automatically or lets the user add it.

If you do not set the host attribute, Kanzi Studio adds the property as a frequently used property to the nodes of the type for which you created the property type and lets the user add the property to any other types of nodes.

Syntax metadata.host = "nodeType:addition";

Values

nodeType Type of the node for which you want Kanzi Studio to make the property available.

addition

How Kanzi Studio adds the property or lets the user add it:

user lets the user add the property using the context menu or the Add Properties window.
context lets the user add the property in the same ways as user, and also using the context tab of the Add Properties window.
freq adds the property as a frequently used property, marked with in the Properties. The user can also add the property in the same ways as with context.
auto adds the property automatically.
fixed adds the property automatically and does not let the user remove the property.

You can set multiple nodeType:addition pairs separated with commas.

Examples

// Adds the property as a frequently used property for all 2D nodes.
metadata.host = "Node2D:freq";

// Adds the property automatically for all VideoView2D nodes and lets the user add the property for Image nodes.
metadata.host = "VideoView2D:auto,Image2D:user";

editor

Sets the editor type Kanzi Studio users use to set the value for the property. If you do not set an editor, Kanzi assigns a default editor.

If you set the valueProvider attribute to PropertyType or StringList, do not set the editor type. Kanzi Studio assigns the correct editor automatically.

For a list of Kanzi Studio property editors, see Kanzi Studio property editors for property types declared in Kanzi Engine plugins.

Syntax metadata.editor = "editor";

Values

editor Kanzi Studio property editor name. See Kanzi Studio property editors for property types declared in Kanzi Engine plugins.

Examples

// Set editor to BrowseFileTextEditor which contains a text box with a Browse button next to it.
metadata.editor = "BrowseFileTextEditor";

DefaultValue

Sets the default value of the property or message the way it is shown in Kanzi Studio.

Syntax metadata["DefaultValue"] = "value";

Values

value The default value of the property or message in Kanzi Studio

Examples

// Set the default value of a string property in Kanzi Studio to video.mp4.
metadata["DefaultValue"] = "video.mp4";

// Set the default value of a float property in Kanzi Studio to 180.
metadata["DefaultValue"] = "180";

LowerBound

Sets the lowest value the property can have in Kanzi Studio. Use LowerBound with int and float property types. See also UpperBound and Step.

Syntax metadata["LowerBound"] = "value";

Values

value The lowest value the property can have

Examples

// Set the lowest value the property can have to 0.
metadata["LowerBound"] = "0";

UpperBound

Sets the highest value the property can have in Kanzi Studio. Use UpperBound with int and float property types. See also LowerBound and Step.

Syntax metadata["UpperBound"] = "value";

Values

value The highest value the property can have

Examples

// Set the highest value the property can have to 360.
metadata["UpperBound"] = "360";

Step

Sets the amount by which the property value changes when a Kanzi Studio user edits it. Use Step with int and float property types. See also LowerBound and UpperBound.

Syntax metadata["Step"] = "value";

Values

value The amount by which the property value changes when a Kanzi Studio user edits it

Examples

// Set the amount by which the property value changes when a Kanzi Studio user edits it to 10.
metadata["Step"] = "10";

Sendable

Sets whether Kanzi Studio shows the message as an action in the trigger actions dropdown menu.

Syntax metadata["Sendable"] = "value"

Values

`True`	Show the message as an action. Default value.
`False`	Do not show the message as an action.

Examples

// Do not show the message as an action.
metadata["Sendable"] = "False";

Listenable

Sets whether Kanzi Studio shows the message as a trigger in the Add Triggers window and Add Trigger context menu.

Syntax metadata["Listenable"] = "value"

Values

`True`	Show the message as a trigger. Default value.
`False`	Do not show the message as a trigger.

Examples

// Do not show the message as a trigger.
metadata["Listenable"] = "False";

SortingIndex

Sets the position of the property in its property category shown in the Kanzi Studio Properties window. By default Kanzi Studio orders property types within a property category according to their order in the metaclass definition. See category.

Syntax metadata["SortingIndex"] = "index"

Values

index Position of the property in its property category shown in Kanzi Studio

Examples

// Show the property as the first property in its property category.
metadata["SortingIndex"] = "1";

studioVisibility

Sets whether the property or message is available in Kanzi Studio.

Syntax metadata["StudioVisibility"] = "value"

Values

`Visible`	Show the property or message in Kanzi Studio. Default value.
`UserHidden`	Hide the property or message from the Kanzi Studio user, but keep Kanzi Studio aware of the property or message.
`Hidden`	Make Kanzi Studio unaware of the property or message and do not include the property or message in the kzb file. You can use this value for properties and messages that implement internal functionality of the plugin and do not need to be set in Kanzi Studio.

Examples

// Make Kanzi Studio unaware of the property.
metadata["StudioVisibility"] = "Hidden";

LegacyName

Sets the name of the property type or message in earlier versions of the Kanzi Engine plugin.

When you rename a property type or message, use LegacyName to inform Kanzi Studio about the change. When a Kanzi Studio user updates the Kanzi Engine plugin in a Kanzi Studio project, Kanzi Studio renames all instances of the property type or message in that project.

Syntax metadata["LegacyName"] = "name"

Values

name Name of the property type or message in earlier versions of the plugin. Separate legacy names with semicolons.

Examples

// Give Kanzi Studio the name of the property type or message in the earlier versions of the plugin.
metadata["LegacyName"] = "MyOldPropertyName";